Restructure Python custom operators guide#3916
Conversation
Split the custom Python operators tutorial into an overview plus focused pages for functional operators, mutable operators, and optional registrations. Emphasize required schema and mutation/aliasing contracts, opcheck validation, fake kernels for torch.compile/export, and 2.13-only in-place/out custom operator behavior. Add the new pages under the custom operators landing page so the left navigation exposes a nested custom-ops section and users can move through the guide in order. Validated with lintrunner -m main and make clean-cache && make html-noplot.
🔗 Helpful Links🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/tutorials/3916
Note: Links to docs will display an error until the docs builds have been completed. ✅ No FailuresAs of commit ebf88d6 with merge base 326edb0 ( This comment was automatically generated by Dr. CI and updates every 15 minutes. |
| Functional Python Custom Operators for torch.compile | ||
| ==================================================== |
There was a problem hiding this comment.
remove "for torch.compile"
| Choose one path: | ||
|
|
There was a problem hiding this comment.
This table is a little squashed, can we improve it?
| Decide the schema and mutation/aliasing contract before writing registrations. | ||
| PyTorch uses the schema and registrations to reason about aliasing; it does not | ||
| infer the contract from the Python body. | ||
|
|
There was a problem hiding this comment.
should define what aliasing is in PyTorch.
|
full disclosure I didn't go through the PR in detail and am doing that in the background, but if you folks can review this at the same time I can get my agent to fix all the comments at once |
| input tensor, a view of an input, or two outputs that alias each other. | ||
| * A mutable custom operator must list every mutated argument in ``mutates_args``. | ||
| * A fake kernel must return tensors with the same metadata as the real kernel: | ||
| shape, dtype, device, layout, strides, and storage offset when relevant. |
There was a problem hiding this comment.
Is there an example of strides? We should provide a code example of a bad example and what the fix is
| Mutable Python Custom Operators | ||
| =============================== | ||
|
|
||
| The functional page wrapped ``numpy.sin`` as an operator that returns a fresh |
There was a problem hiding this comment.
"the functional page" is a bit weird to read, link to it or something
| # needs this contract for functionalization, fake tensors, ``torch.compile``, | ||
| # and autograd. | ||
| # | ||
| # If the operator does not mutate a Tensor input, use the functional operator |
There was a problem hiding this comment.
if the operator does not mutate any Tensor input,
| # If the operator mutates keyword-only ``out=`` Tensor arguments and returns | ||
| # them, use a tagged ``out=`` operator, starting in PyTorch 2.13. Do not read | ||
| # from the ``out=`` tensors. |
There was a problem hiding this comment.
combine this into one sentence somehow. Part of the definition of out= operator means that the out= tensor is write-only (no reads)
1 participant
Split the custom Python operators tutorial into an overview plus focused pages for functional operators, mutable operators, and optional registrations. Emphasize required schema and mutation/aliasing contracts, opcheck validation, fake kernels for torch.compile/export, and 2.13-only in-place/out custom operator behavior.
Add the new pages under the custom operators landing page so the left navigation exposes a nested custom-ops section and users can move through the guide in order.
Validated with lintrunner -m main and make clean-cache && make html-noplot.
This was generated by codex and I didn't read it carefully (but I did read most of it).